package me.softwareengineer.guice.rendering.domain;

import java.util.Map;

/**
 * Metadata is used to store supplymentery information
 * in the elements. 
 * For example, the backup version of the element so that the parser can rerender the content of 
 * the element again. As shown below:
 * <pre>
 * <code> 
 * VirtualElement e = new VirtualElement();
 * e.addMetaData("backupVersion", e.clone());
 * </code>
 * To get the stored backup, we can use the following command:
 * <code>
 * 	Element element = (Element) e.getMetaData("backupVersion");
 * </code>
 * 
 * </pre>
 * 
 * @author yad.tahir
 * @since 1.0
 */
public interface HasMetaData {
	/**
	 * Copies the provided metdadata to the element
	 * 
	 * @param metaData
	 */
	public void addMetaData(HasMetaData metaData);

	/**
	 * Adds the given metadata records to the metadata
	 * 
	 * @param records
	 *            the metadata records to be added to the element
	 */
	public void addMetaData(Map<String, Object> records);

	/**
	 * Adds metadata to the element
	 * 
	 * @param key
	 *            the key to the metadata
	 * @param value
	 *            the value of the metadata
	 */
	public void addMetaData(String key, Object value);

	/**
	 * 
	 * @param key
	 * @return true if the metadata of to corresponding key exists. Otherwise,
	 *         false
	 */
	public boolean containsMetadata(String key);

	/**
	 * 
	 * @return all the metadata of the element. The returned map is an
	 *         unmodifiable map/
	 */
	public Map<String, Object> getAllMetaData();

	/**
	 * Gets metadata for the provided key
	 * 
	 * @param key
	 * @return
	 */
	public Object getMetaData(String key);

	/**
	 * Removes the metadata to the corresponding key
	 * 
	 * @param key
	 *            the key of the metadata record
	 */
	public void removeMetaData(String key);
}
